<html>
<head>
<title>CQ/XML - ClearQuest Root Element</title>
<link rel='stylesheet' type='text/css' href='cqxmldocs.css'/>
</head>

<body>
<center>
  <h1>ClearQuest/XML Interface User Guide</h1>
</center>

<h2>ClearQuest Root Element</h2>
<p>
Like all well-formed XML, the CQ/XML format contains one root element.  The name of that element is '<span class='inline'>ClearQuest</span>'.  The ClearQuest element is also responsible for passing login information to the ClearQuest server via its attributes.  The ClearQuest element has four required and one optional attribute.
<center>
  <table cellspacing='0' cellpadding='2' border='1'>
  <tr>
    <th>Required&nbsp;Attribute</th>
    <th>Description</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>login</td>
    <td>the ClearQuest user login</td>
    <td>&nbsp;</td>
  </tr>
  <tr>
    <td>password
      <br>
      <i>- or -</i>
      <br>
      encrypted
    </td>
    <td>
      the (encrypted) ClearQuest user password
    </td>
    <td>
      <br>
      <br>
      encryption keys must be syncronized with a <a href='mailto:cqsupport@domain.com'>CQ admin</a>
  </tr>
  <tr>
    <td>db</td>
    <td>the ClearQuest database to login to</td>
    <td>valid values: <span class='inline'>pract</span> or <span class='inline'>prodd</span></td>
  </tr>
  <tr>
    <td>repo</td>
    <td>the ClearQuest database repository</td>
    <td>valid values: <span class='inline'>practice</span> or <span class='inline'>prodr</span></td>
  </tr>
  <tr>
    <th>Optional&nbsp;Attribute</th>
    <th>Description</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>email-fail</td>
    <td>email address to send errors to on '<span class='inline'>queued actions</span>'</td>
    <td>&nbsp;</td>
  </tr>
  </table>
</center>
</p>
<p class='hilite'>
Although the CQ/XML Interface can prohibit actions against defects based on its <a href='common.html#misc_perm'>permissions model</a>, it is still possible to corrupt a large number of defects rather quickly if you are not careful.  Therefore, before deploying into production you should <b>do all development and testing against the practice database</b> (<span class='src'><span class="atrb">db</span>=<span class="atrbval">'pract'</span> <span class="atrb">repo</span>=<span class="atrbval">'practice'</span></span>).  If you corrupt data in the <i>production</i> database <b>we will be unable to back out the changes you have introduced</b>.
</p>
<p>
Since you can only have one root element, to send multiple commands create multiple defect/query/info elements within one root element or make multiple connections to the server.  See also: 
  <a href='common.html'>Common Issues, Mistakes &amp; Caveats</a>.
</p>
<h2>Root Element Examples</h2>
<p>
Standard login:
<br>
&nbsp;&nbsp;
<span class='src'>
  &lt;<span class="elem">ClearQuest</span> <span class="atrb">login</span>=<span class="atrbval">'cq_user'</span> <span class="atrb">password</span>=<span class="atrbval">'password'</span> <span class="atrb">db</span>=<span class="atrbval">'pract'</span> <span class="atrb">repo</span>=<span class="atrbval">'practice'</span>&gt;
</span>
</p>
<p>
Login with encrypted password:
<br>
&nbsp;&nbsp;
<span class='src'>
  &lt;<span class="elem">ClearQuest</span> <span class="atrb">login</span>=<span class="atrbval">'cq_user'</span> <span class="atrb">encrypted</span>=<span class="atrbval">'&amp;&#177;&#191;&#254;A'</span> <span class="atrb">db</span>=<span class="atrbval">'pract'</span> <span class="atrb">repo</span>=<span class="atrbval">'practice'</span>&gt;
</span>
</p>
<p>
Login with email failure notification:
<br>
&nbsp;&nbsp;
<span class='src'>
  &lt;<span class="elem">ClearQuest</span> <span class="atrb">login</span>=<span class="atrbval">'cq_user'</span> <span class="atrb">password</span>=<span class="atrbval">'password'</span> <span class="atrb">db</span>=<span class="atrbval">'pract'</span> <span class="atrb">repo</span>=<span class="atrbval">'practice'</span> <span class="atrb">email-fail</span>=<span class="atrbval">'cq_user@domain.com'</span>&gt;
</span>
</p>

<h2>Caveats</h2>
<p>
<ul>
  <li>Since the '<span class='inline'>password</span>' or '<span class='inline'>encrypted</span>' attribute is required, it must contain a value.  In other words, <i>blank passwords are not permitted</i>.</li>
  <li>The '<span class='inline'>password</span>' or '<span class='inline'>encrypted</span>' value cannot contain the greater-than symbol ('<span class='src'>&gt;</span>').</li>
</ul>
</p>

<h2>Up Next</h2>
<p>
Now that you can login, the next chapter <a href='defect.html'>Defect Elements</a> will show how to work with specific defects.
</p>

<!-- footer -->
<table class='ftr'>
<tr>
  <td class='ftrl'><a href='connect.html' class='ftr'><img src='arrow-l.gif'/> Connecting to the CQ/XML Server</a></td>
  <td class='ftrc'><a href='index.html' class='ftr'><img src='arrow-u.gif'/> Table of Contents</a></td>
  <td class='ftrr'><a href='defect.html' class='ftr'>Defect Elements <img src='arrow-r.gif'/></a></td>
</tr>
</table>
</body>
</html>
